{
    title: "Publishing Packages",
    crumbs: [
        { "Developer's Guide": "index.html" },
    ],
}
            <h1>Publishing Packages</h1>

            <p>You can publish a package for use by Pak in one of three package catalogs:</p>
            <ul>
                <li><a href="http://bower.io/search/">Bower Catalog</a></li>
                <li><a href="http://npmjs.org/">NPM Catalog</a></li>
                <li><a href="http://embedthis.com/catalog/">Pak Catalog</a></li>
            </ul>
            <p>This document describes the process for creating a package in the Pak catalog. Consult the relevant
                <a href="http://npmjs.org/">NPM</a> or <a href="http://bower.io/">Bower</a> documentation for 
                creating packages in those catalogs.</p>

            <h2>Publishing to the Pak Catalog</h2>
            <p>To publish a new package in the Pak catalog, <a href="creating.html">create your package.json</a> 
            and then run <em>pak publish</em> in your application directory.</p>
            <pre class="code">$ pak publish

$ pak publish NAME ENDPOINT EMAIL [OVERRIDE]</pre>

            <p>In the first example, the package name, repository endpoint and author's email address will be extracted 
            from the <em>package.json</em>. The third example supplies the name, endpoint and email. You will be prompted
            to enter a password to secure management of the package. You can supply a file containing the password via
            the <em>--password password</em> option. Choose and protect your password very carefully. You may 
            use it to modify or retract your package from the catalog.</p>

            <p>The package name should be a globally unique name for your package. It may contain <em>-</em>, 
            <em>_</em> or <em>.</em> characters. Check the <a href="http://embedthis.com/catalog">Pak Catalog</a> 
            for currently published Pak names to ensure your chosen name is unique. Note that Pak names that start 
            with <em>appweb</em>, <em>esp</em>, <em>ejs</em>, <em>embedthis</em>, <em>exp</em>, <em>expansive</em>, 
            <em>go</em>, <em>goahead</em>, <em>makeme</em>, <em>me</em> and <em>pak</em> are reserved. </p>

            <p>The email address should be that of the person responsible for the catalog entry for the package. 
                This email address will be used for password reset requests. </p>

            <p>The package endpoint is a valid GitHub account or endpoint that hosts your package contents. For example:</p>
<pre class="code">pak publish jquery/jquery ...
pak publish https://github.com/jquery/jquery.git ...
pak publish git@github.com:jquery/jquery ...
pak publish git@github.com:jquery/jquery ...</pre>

            <p>To publish a package that is hosted on <a href="http://npmjs.org">NPM</a>, use an <em>@npm:</em> package
            alias to query the NPM catalog. For example:</p>

            <pre class="code">pak publish @npm:jquery name@example.com</pre>

            <h2>Package Aliases</h2>
            <p>You can publish an alias entry in the catalog that redirects Pak to use another package name. 
            To create an alias, simply use an <em>@</em> prefix on the endpoint. For example:</p>

            <pre class="code">pak publish my-angular @angular ...</pre>

            <p>When Pak installs <em>my-angular</em> it will redirect and search for the <em>angular</em> package 
            and install it instead. You can use a catalog prefix <em>pak:</em>, <em>bower:</em> and <em>npm:</em> to direct 
            Pak to search in the designated catalog. For example:</p>

            <pre class="code">pak publish my-angular @bower:angular ...</pre>

            <p>This will search for <em>angular</em> in the Bower catalog.</p>

            <a name="override"></a>
            <h2>Override Packages</h2>
            <p>Sometimes you may need to create a package from third-party source that you cannot modify or control.
            The package source may not even have its own <em>package.json</em> file. To support wrapping such existing 
            packages, you can create an entry in the Pak catalog with an override package.json file. 
            This override file is blended into the package's package.json when it is saved to the Pak cache. 
            If the package does not have its own package.json, then this file will be used to create a package.json. 
            For example:</p>

            <pre class="code">pak publish my-openssl openssl/openssl me@example.com &rarr;
    http://example.com/openssl.json</pre>

            <p>You can directly access override files in GitHub via the <em>raw.githubusercontent.com</em> site.
            For example: <em>raw.githubusercontent.com/embedthis/pak/master/overrides/openssl.json</em>.</p>

            <p>Pak considers override instructions from several sources (in order):</p>
            <ul>
                <li>Override instructions from the Pak catalog.</li>
                <li>Over instructions in a local package override file under <em>~/.pak/overrides/NAME.json</em></li>
                <li>Override instructions in your application's <em>package.json</em> file.</li>
            </ul>

            <h3>Override Files</h3>
            <p>Override files in the <em>~/.pak/override</em> directory or in the Pak catalog have a slightly 
            different syntax so they can provide different overrides for various versions of a package. One 
            override file can provide override configuration for all versions of a package and for various 
            endpoints hosting the package. </p>
            <p>For example, here is a portion of the jQuery override file in the 
            Pak catalog. It has different configuration for version 1.x and 2.x and provides unique configuration
            when hosted from NPM:</p>
            <pre class="code">{
    "jquery/jquery": {
        "&gt;=2.1.0": {
            "pak": {
                "export": {
                    "from":  "dist/jquery.*",
                    "trim": 1
                }
            }
        },
        "&gt;=1.11.0": {
            "pak": {
                "export": {
                    "from":  "dist/jquery.js",
                    "trim": 1
                }
            }
        }
    },
    "@npm/jquery": {
        ...
    }
}
</pre>
            <p>An override file is a hash of endpoints that provide the package. Inside each endpoint property hash is
            a set of configurations for different version expressions.
            See <a href="../users/versions.html#expressions">Version Expressions</a> for details on the version 
            expression syntax.</p>
            <p>Here are some example override files from the Pak Catalog:</p>
            <ul>
                <li><a href="https://github.com/embedthis/pak-overrides/tree/master/angular.json">Angular</a></li>
                <li><a href="https://github.com/embedthis/pak-overrides/tree/master/angular-route.json">Angular Route</a></li>
                <li><a href="https://github.com/embedthis/pak-overrides/tree/master/bootstrap.json">Bootstrap</a></li>
                <li><a href="https://github.com/embedthis/pak-overrides/tree/master/font-awesome.json">Font Awesome</a></li>
                <li><a href="https://github.com/embedthis/pak-overrides/tree/master/jquery.json">JQuery</a></li>
                <li><a href="https://github.com/embedthis/pak-overrides/tree/master/semantic-ui-css.json">Semantic-UI</a></li>
            </ul>
